home *** CD-ROM | disk | FTP | other *** search
/ Software of the Month Club 1998 June / Software of the Month Club 1998 June.iso / mac / Business / Hi's Universal Saver / Menu Events 1.3 / Menu Events Help / Menu Events Help.rsrc / STR#_1029.txt < prev    next >
Encoding:
Text File  |  1998-04-13  |  16.3 KB  |  931 lines
  1. 
  2.  
  3. 
  4.  
  5. §
  6.  
  7. §
  8.  
  9. ├ÑMenu Events Suite
  10.  
  11. 
  12.  
  13. 
  14.  
  15. The following is a formal description of the Menu Events suite, in the form
  16.  
  17. used in the Apple Event Registry.
  18.  
  19. 
  20.  
  21. 
  22.  
  23. NOTE:  The C header file ΓÇ£Menu Events.hΓÇ¥┬ácontains the constant
  24.  
  25. definitions which appear here.  The ΓÇ£Menu Events Scripting AdditionΓÇ¥ file
  26.  
  27. contains an 'aete' resource which records the following dictionary
  28.  
  29. information, for the benefit of scripting packages such as AppleScript.
  30.  
  31. This package also includes a sample script, ΓÇ£Menu Events Sample
  32.  
  33. Script,ΓÇ¥ which demonstrates the usage of the following events and
  34.  
  35. parameters.
  36.  
  37. 
  38.  
  39. 
  40.  
  41. 
  42.  
  43. xApple events defined in the Menu Events suite
  44.  
  45. 
  46.  
  47. Name              Requested action
  48.  
  49. 
  50.  
  51. 
  52.  
  53. Query Menu List   List all application-defined menus
  54.  
  55. Query Menu        List all items in a menu
  56.  
  57. Select Menu Item  Perform a menu command
  58.  
  59. 
  60.  
  61. 
  62.  
  63. 
  64.  
  65. xQuery Menu List - list all application-defined menus
  66.  
  67. 
  68.  
  69. A Query Menu List Apple event asks the application to return a list of
  70.  
  71. records containing information about all menus defined by the application
  72.  
  73. in its menu bar.  This information includes the Apple menu, but not the
  74.  
  75. Help, Keyboard, or Application menus.
  76.  
  77. 
  78.  
  79. 
  80.  
  81. Event Class       kMEEventClass
  82.  
  83. 
  84.  
  85. Event ID          kAEMEQueryMenuList
  86.  
  87. 
  88.  
  89. Parameters        none
  90.  
  91. 
  92.  
  93. Reply Parameters
  94.  
  95. 
  96.  
  97. 
  98.  
  99. keyDirectObject
  100.  
  101.                   Description:  A list of Apple event
  102.  
  103.                                 records, one for each
  104.  
  105.                                 menu, each containing the
  106.  
  107.                                 following parameters
  108.  
  109.                   Descriptor Type:  typeAEList
  110.  
  111.                   Required or Optional?  Required
  112.  
  113. 
  114.  
  115. 
  116.  
  117. 
  118.  
  119.    keyMenuID
  120.  
  121.                   Description:  The ID of the menu, not
  122.  
  123.                                 necessarily equal to the
  124.  
  125.                                 ID of the 'MENU' resource
  126.  
  127.                                 it may have come from
  128.  
  129.                   Descriptor Type:  typeShortInteger
  130.  
  131.                   Required or Optional?  Required
  132.  
  133. 
  134.  
  135. 
  136.  
  137.    keyMenuTitle
  138.  
  139.                   Description:  The title of the menu, as
  140.  
  141.                                 it appears in the menu bar
  142.  
  143.                   Descriptor Type:  typeChar
  144.  
  145.                   Required or Optional?  Required
  146.  
  147. 
  148.  
  149. 
  150.  
  151.    keyMenuEnabled
  152.  
  153.                   Description:  Whether or not the menu, as
  154.  
  155.                                 a whole, is enabled
  156.  
  157.                   Descriptor Type:  typeBoolean
  158.  
  159.                   Required or Optional?  Required
  160.  
  161. 
  162.  
  163. 
  164.  
  165.    keyMenuMDEFID
  166.  
  167.                   Description:  The ID of the menu definition
  168.  
  169.                                 procedure ('MDEF') resource,
  170.  
  171.                                 ordinarily 0; -1 signifies
  172.  
  173.                                 that the definition procedure
  174.  
  175.                                 is not a resource
  176.  
  177.                   Descriptor Type:  typeShortInteger
  178.  
  179.                   Required or Optional?  Required
  180.  
  181. 
  182.  
  183. 
  184.  
  185. 
  186.  
  187. keyMenuEventsTattoo
  188.  
  189.                   Description:  A null parameter to verify
  190.  
  191.                                 that Menu Events handled
  192.  
  193.                                 the event
  194.  
  195.                   Descriptor Type:  typeNull
  196.  
  197.                   Required or Optional?  Required
  198.  
  199. 
  200.  
  201. 
  202.  
  203. 
  204.  
  205. Result Codes
  206.  
  207.                   mBarNFnd        -126    The application has
  208.  
  209.                                           no menu bar
  210.  
  211. 
  212.  
  213. 
  214.  
  215. 
  216.  
  217. 
  218.  
  219. xQuery Menu - list all items in a menu
  220.  
  221. 
  222.  
  223. A Query Menu Apple event asks the application to return a list of records
  224.  
  225. containing information about all items in a given menu (selected by ID
  226.  
  227. and/or title).  It requests user interaction to bring the application to the
  228.  
  229. front, then posts mouse events to simulate a click in the menu bar, with
  230.  
  231. modifier key states as specified, to force the application to update its
  232.  
  233. menus, then reads the items from the given menu.  This information is
  234.  
  235. complete enough to reconstruct the menu, except for the icon resources
  236.  
  237. referenced by the keyMenuItemIcon parameter.
  238.  
  239. 
  240.  
  241. 
  242.  
  243. Event Class       kMEEventClass
  244.  
  245. 
  246.  
  247. Event ID          kAEMEQueryMenu
  248.  
  249. 
  250.  
  251. Parameters
  252.  
  253. 
  254.  
  255. 
  256.  
  257. keyMenuID
  258.  
  259.                   Description:  The ID of the menu, as
  260.  
  261.                                 returned by a Query Menu
  262.  
  263.                                 List Apple event
  264.  
  265.                   Descriptor Type:  typeShortInteger
  266.  
  267.                   Required or Optional?  Optional
  268.  
  269. 
  270.  
  271. 
  272.  
  273. keyMenuTitle
  274.  
  275.                   Description:  The title of the menu, as
  276.  
  277.                                 returned by a Query Menu
  278.  
  279.                                 List Apple event
  280.  
  281.                   Descriptor Type:  typeChar
  282.  
  283.                   Required or Optional?  Optional
  284.  
  285. 
  286.  
  287. NOTE:  Either keyMenuID or keyMenuTitle, or both, must be specified.
  288.  
  289. 
  290.  
  291. keyShiftKeyPressed
  292.  
  293.                   Description:  Whether the Shift key is
  294.  
  295.                                 pressed at the time of the
  296.  
  297.                                 simulated menu bar click
  298.  
  299.                   Descriptor Type:  typeBoolean
  300.  
  301.                   Required or Optional?  Optional
  302.  
  303.                   Default Value:  false
  304.  
  305. 
  306.  
  307. 
  308.  
  309. keyControlKeyPressed
  310.  
  311.                   Description:  Whether the Control key is
  312.  
  313.                                 pressed at the time of the
  314.  
  315.                                 simulated menu bar click
  316.  
  317.                   Descriptor Type:  typeBoolean
  318.  
  319.                   Required or Optional?  Optional
  320.  
  321.                   Default Value:  false
  322.  
  323. 
  324.  
  325. 
  326.  
  327. keyOptionKeyPressed
  328.  
  329.                   Description:  Whether the Option key is
  330.  
  331.                                 pressed at the time of the
  332.  
  333.                                 simulated menu bar click
  334.  
  335.                   Descriptor Type:  typeBoolean
  336.  
  337.                   Required or Optional?  Optional
  338.  
  339.                   Default Value:  false
  340.  
  341. 
  342.  
  343. 
  344.  
  345. keyCommandKeyPressed
  346.  
  347.                   Description:  Whether the Command key is
  348.  
  349.                                 pressed at the time of the
  350.  
  351.                                 simulated menu bar click
  352.  
  353.                   Descriptor Type:  typeBoolean
  354.  
  355.                   Required or Optional?  Optional
  356.  
  357.                   Default Value:  false
  358.  
  359. 
  360.  
  361. 
  362.  
  363. Reply Parameters
  364.  
  365. 
  366.  
  367. 
  368.  
  369. keyDirectObject
  370.  
  371.                   Description:  A list of Apple event
  372.  
  373.                                 records, one for each
  374.  
  375.                                 item, each containing the
  376.  
  377.                                 following parameters
  378.  
  379.                   Descriptor Type:  typeAEList
  380.  
  381.                   Required or Optional?  Required
  382.  
  383. 
  384.  
  385. 
  386.  
  387. 
  388.  
  389.    keyMenuItemID
  390.  
  391.                   Description:  The ID of the item, numbered
  392.  
  393.                                 from 1 at the top of the menu
  394.  
  395.                   Descriptor Type:  typeShortInteger
  396.  
  397.                   Required or Optional?  Required
  398.  
  399. 
  400.  
  401. 
  402.  
  403.    keyMenuItemText
  404.  
  405.                   Description:  The text of the item, as
  406.  
  407.                                 it appears in the menu
  408.  
  409.                   Descriptor Type:  typeChar
  410.  
  411.                   Required or Optional?  Required
  412.  
  413. 
  414.  
  415. 
  416.  
  417.    keyMenuItemEnabled
  418.  
  419.                   Description:  Whether or not the item is
  420.  
  421.                                 enabled
  422.  
  423.                   Descriptor Type:  typeBoolean
  424.  
  425.                   Required or Optional?  Required
  426.  
  427. 
  428.  
  429. 
  430.  
  431.    keyMenuItemMark
  432.  
  433.                   Description:  The mark character of the
  434.  
  435.                                 item, in the lower byte
  436.  
  437.                   Descriptor Type:  typeShortInteger
  438.  
  439.                   Required or Optional?  Required
  440.  
  441. 
  442.  
  443. 
  444.  
  445.    keyMenuItemIcon
  446.  
  447.                   Description:  The icon number of the item,
  448.  
  449.                                 which is 256 less than the
  450.  
  451.                                 resource ID of the 'ICON' or
  452.  
  453.                                 'cicn' resource
  454.  
  455.                   Descriptor Type:  typeShortInteger
  456.  
  457.                   Required or Optional?  Required
  458.  
  459. 
  460.  
  461. 
  462.  
  463.    keyMenuItemStyle
  464.  
  465.                   Description:  The style value of the item,
  466.  
  467.                                 in the lower byte
  468.  
  469.                   Descriptor Type:  typeShortInteger
  470.  
  471.                   Required or Optional?  Required
  472.  
  473. 
  474.  
  475. 
  476.  
  477.    keyMenuItemCmd
  478.  
  479.                   Description:  The Command-key equivalent
  480.  
  481.                                 character of the item, in the
  482.  
  483.                                 lower byte
  484.  
  485.                   Descriptor Type:  typeShortInteger
  486.  
  487.                   Required or Optional?  Required
  488.  
  489. 
  490.  
  491. 
  492.  
  493. 
  494.  
  495. keyMenuEventsTattoo
  496.  
  497.                   Description:  A null parameter to verify
  498.  
  499.                                 that Menu Events handled
  500.  
  501.                                 the event
  502.  
  503.                   Descriptor Type:  typeNull
  504.  
  505.                   Required or Optional?  Required
  506.  
  507. 
  508.  
  509. 
  510.  
  511. 
  512.  
  513. Result Codes
  514.  
  515.                   mBarNFnd        -126    The application has
  516.  
  517.                                           no menu bar
  518.  
  519. 
  520.  
  521. 
  522.  
  523.                   errAENoUserInteraction
  524.  
  525.                                   -1713   The application is
  526.  
  527.                                           refusing to interact
  528.  
  529.                                           with other processes
  530.  
  531.                                           or (if Menu Events
  532.  
  533.                                           extension is locked)
  534.  
  535.                                           with remote processes
  536.  
  537. 
  538.  
  539. 
  540.  
  541.                   noSuchMenuErr   -15950  The application has
  542.  
  543.                                           no such menu
  544.  
  545. 
  546.  
  547. 
  548.  
  549.                   menuMismatchErr
  550.  
  551.                                   -15955  The given menu ID
  552.  
  553.                                           and menu title
  554.  
  555.                                           do not match
  556.  
  557. 
  558.  
  559. 
  560.  
  561. 
  562.  
  563. 
  564.  
  565. xSelect Menu Item - perform a menu command
  566.  
  567. 
  568.  
  569. A Select Menu Item event simulates the selection of a command (selected
  570.  
  571. by item ID and/or item text) from a menu (selected by ID and/or title).  It
  572.  
  573. requests user interaction to bring the application to the front, then posts
  574.  
  575. mouse events to simulate the selection of the given menu item, with
  576.  
  577. modifier key states as specified.  If the Menu event is correctly handled,
  578.  
  579. and the application reacts to the mouse events in the usual way, the result
  580.  
  581. is as if the user had actually selected that menu item.  Interaction will fail
  582.  
  583. if the application refuses to interact with other processes
  584.  
  585. (kAEInteractWithSelf mode), or, if the application is on another machine
  586.  
  587. and the Menu Events extension has been locked, if it refuses to interact
  588.  
  589. with remote processes (kAEInteractWithLocal mode).
  590.  
  591. 
  592.  
  593. Event Class       kMEEventClass
  594.  
  595. 
  596.  
  597. Event ID          kAEMESelectMenuItem
  598.  
  599. 
  600.  
  601. Parameters
  602.  
  603. 
  604.  
  605. 
  606.  
  607. keyMenuID
  608.  
  609.                   Description:  The ID of the menu, as
  610.  
  611.                                 returned by a Query Menu
  612.  
  613.                                 List Apple event
  614.  
  615.                   Descriptor Type:  typeShortInteger
  616.  
  617.                   Required or Optional?  Required
  618.  
  619. 
  620.  
  621. 
  622.  
  623. keyMenuTitle
  624.  
  625.                   Description:  The title of the menu, as
  626.  
  627.                                 returned by a Query Menu
  628.  
  629.                                 List Apple event
  630.  
  631.                   Descriptor Type:  typeChar
  632.  
  633.                   Required or Optional?  Optional
  634.  
  635. 
  636.  
  637. NOTE:  Either keyMenuID or keyMenuTitle, or both, must be specified.
  638.  
  639. 
  640.  
  641. keyMenuItemID
  642.  
  643.                   Description:  The ID of the item, numbered
  644.  
  645.                                 from 1 at the top of the menu
  646.  
  647.                   Descriptor Type:  typeShortInteger
  648.  
  649.                   Required or Optional?  Optional
  650.  
  651. 
  652.  
  653. 
  654.  
  655. keyMenuItemText
  656.  
  657.                   Description:  The text of the item, as
  658.  
  659.                                 it appears in the menu
  660.  
  661.                   Descriptor Type:  typeChar
  662.  
  663.                   Required or Optional?  Optional
  664.  
  665. 
  666.  
  667. NOTE:  Either keyMenuItemID or keyMenuItemText, or both, must be
  668.  
  669. specified.
  670.  
  671. 
  672.  
  673. keyShiftKeyPressed
  674.  
  675.                   Description:  Whether the Shift key is
  676.  
  677.                                 pressed at the time of the
  678.  
  679.                                 simulated menu selection
  680.  
  681.                   Descriptor Type:  typeBoolean
  682.  
  683.                   Required or Optional?  Optional
  684.  
  685.                   Default Value:  false
  686.  
  687. 
  688.  
  689. 
  690.  
  691. keyControlKeyPressed
  692.  
  693.                   Description:  Whether the Control key is
  694.  
  695.                                 pressed at the time of the
  696.  
  697.                                 simulated menu selection
  698.  
  699.                   Descriptor Type:  typeBoolean
  700.  
  701.                   Required or Optional?  Optional
  702.  
  703.                   Default Value:  false
  704.  
  705. 
  706.  
  707. 
  708.  
  709. keyOptionKeyPressed
  710.  
  711.                   Description:  Whether the Option key is
  712.  
  713.                                 pressed at the time of the
  714.  
  715.                                 simulated menu selection
  716.  
  717.                   Descriptor Type:  typeBoolean
  718.  
  719.                   Required or Optional?  Optional
  720.  
  721.                   Default Value:  false
  722.  
  723. 
  724.  
  725. 
  726.  
  727. keyCommandKeyPressed
  728.  
  729.                   Description:  Whether the Command key is
  730.  
  731.                                 pressed at the time of the
  732.  
  733.                                 simulated menu selection
  734.  
  735.                   Descriptor Type:  typeBoolean
  736.  
  737.                   Required or Optional?  Optional
  738.  
  739.                   Default Value:  false
  740.  
  741. 
  742.  
  743. 
  744.  
  745. Reply Parameters
  746.  
  747. 
  748.  
  749. 
  750.  
  751. keyMenuEventsTattoo
  752.  
  753.                   Description:  A null parameter to verify
  754.  
  755.                                 that Menu Events handled
  756.  
  757.                                 the event
  758.  
  759.                   Descriptor Type:  typeNull
  760.  
  761.                   Required or Optional?  Required
  762.  
  763. 
  764.  
  765. 
  766.  
  767. 
  768.  
  769. Result Codes
  770.  
  771.                   mBarNFnd        -126    The application has
  772.  
  773.                                           no menu bar
  774.  
  775. 
  776.  
  777. 
  778.  
  779.                   errAENoUserInteraction
  780.  
  781.                                   -1713   The application is
  782.  
  783.                                           refusing to interact
  784.  
  785.                                           with other processes
  786.  
  787.                                           or (if Menu Events
  788.  
  789.                                           extension is locked)
  790.  
  791.                                           with remote processes
  792.  
  793. 
  794.  
  795. 
  796.  
  797.                   noSuchMenuErr   -15950  The application has
  798.  
  799.                                           no such menu
  800.  
  801. 
  802.  
  803. 
  804.  
  805.                   noSuchMenuItemErr
  806.  
  807.                                   -15951  The menu has no
  808.  
  809.                                           such item
  810.  
  811. 
  812.  
  813. 
  814.  
  815.                   menuItemDisabledErr
  816.  
  817.                                   -15952  The item is
  818.  
  819.                                           disabled
  820.  
  821. 
  822.  
  823. 
  824.  
  825.                   menuEventPendingErr
  826.  
  827.                                   -15953  Another Menu event
  828.  
  829.                                           is already pending
  830.  
  831.                                           on this application
  832.  
  833. 
  834.  
  835. 
  836.  
  837.                   menuMismatchErr
  838.  
  839.                                   -15955  The given menu ID
  840.  
  841.                                           and menu title
  842.  
  843.                                           do not match
  844.  
  845. 
  846.  
  847. 
  848.  
  849.                   menuItemMismatchErr
  850.  
  851.                                   -15956  The given menu item ID
  852.  
  853.                                           and menu item text
  854.  
  855.                                           do not match
  856.  
  857. 
  858.  
  859. 
  860.  
  861. 
  862.  
  863. 
  864.  
  865. xConstants defined in the Menu Events suite
  866.  
  867. 
  868.  
  869. Constant               Value
  870.  
  871. 
  872.  
  873. 
  874.  
  875. kAEMEQueryMenu         'qmn '
  876.  
  877. kAEMEQueryMenuList     'qmn#'
  878.  
  879. kAEMESelectMenuItem    'semi'
  880.  
  881. keyCommandKeyPressed   'comk'
  882.  
  883. keyControlKeyPressed   'conk'
  884.  
  885. keyMenuEnabled         'mnen'
  886.  
  887. keyMenuEventsTattoo    'M├ªnu'
  888.  
  889. keyMenuID              'mnid'
  890.  
  891. keyMenuItemCmd         'micm'
  892.  
  893. keyMenuItemEnabled     'mien'
  894.  
  895. keyMenuItemIcon        'miic'
  896.  
  897. keyMenuItemID          'miid'
  898.  
  899. keyMenuItemMark        'mima'
  900.  
  901. keyMenuItemStyle       'mist'
  902.  
  903. keyMenuItemText        'mite'
  904.  
  905. keyMenuMDEFID          'mndf'
  906.  
  907. keyMenuTitle           'mnti'
  908.  
  909. keyOptionKeyPressed    'optk'
  910.  
  911. keyShiftKeyPressed     'shik'
  912.  
  913. kMEEventClass          'M├ªnu'
  914.  
  915. menuEventPendingErr    -15953
  916.  
  917. menuItemDisabledErr    -15952
  918.  
  919. menuItemMismatchErr    -15956
  920.  
  921. menuMismatchErr        -15955
  922.  
  923. noSuchMenuErr          -15950
  924.  
  925. noSuchMenuItemErr      -15951
  926.  
  927. 
  928.  
  929. 
  930.  
  931.